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Documentation Errata and Change Pages for SunOS 

Release 4.0.3 


Introduction 

The “mini-box” of 4.0.3 release documentation contains this document and two manuals. Installing the SunOS 4.0.3 
and the SunOS 4.0.3 Release Manual. The manuals contain information you will need in order to upgrade your 
system. This document, “Documentation Errata and Change Pages for SunOS Release 4.0.3,” supplements and 
corrects the documentation set for SunOS™ 4.0.3 in the following areas: 

• CG8 Release Notes 

Describes the changes to Pixrect, SunView 1, and Sun diagnostic software to support the new cg8 24-bit 
frame buffer. 

• Sun-2 and Sun-3 Assembler 

Describes changes to the Assembly Language Reference Manual to support the MC68030 microprocessor 
included in the as assembler for Sun-2 and Sun-3 workstations. 

• Device Drivers 

Describes corrections required to parts of Writing Device Drivers. 

Refer also to the READ THIS FIRST document, which is packed in the release-tape box. READ THIS FIRST contains 
information that, because of publication deadlines, could not be included elsewhere. 

eg 8 24-Bit Color 

This section describes the changes implemented in Pixrect, SunView 1, and diagnostic software to support the new 
24-bit frame buffer, the cg8. Refer to the SunView I Programmer’s Guide, the SunView 1 System Programmer’s 
Guide, and the Pixrect Reference Manual for more information about Pixrect and SunView 1 in SunOS 4.0.3. For 
more information about diagnostics, refer to the Sun System Diagnostics manual. 

Overview 

The cg8 color board has three planes: a 24-bit plane to represent true color images, a 1-bit overlay plane for the 
high-speed display of monochrome images, and an enable plane for selecting between the other two planes. 

Pixrect Support 

The changes to the Pixrect package have been deliberately kept to a minimum. The cg8 board stores its color pixels 
in a format called XBGR. Pixrect now understands this format, storing XBGR format pixels in 32-bit pixrects. 
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The true color lookup table is manipulated with two new macros. There is also a new Pixrect planegroup, called 
PIXPG_24BIT_COLOR, which provides access to the cg8 true-color plane. 

XBGR Format 

The Pixrect library already supports 1-bit, 8-bit, and 32-bit-deep pixrects (32 as memory pixrects). Since tme color 
pixrects are stored in a format that is 32 bits deep, there were minimal changes made to the Pixrect library. A new 
type of pixel format, called XBGR is defined to hold true color pixrects. The cg8 stores 24-bit images in this format. 
The format is shown below: 


r - V 

tinclude <pixrect/pixrect_hs.h> 

union fbunit { 

u_int 
struct { 

packed; normal 32-bit pixrects 

u int 

A: 8; the high-order 8 bits are unused 

u_int 

B: 8; 8 bits of blue component 

u_int 

G: 8; 8 bits of green component 

u int 

R: 8; 8 bits of red component 

} 

); 

channel; 

_ J 


The 32-bit word is divided into 4 channels of 8 bits each. The first channel (the high-order 8 bits) is not currently 
used by the cg8. Its value is undefined, and it is reserved for future enhancements. The next channel contains 8 bits 
of the pixel blue component (256 possible values, from 0 to 255, for the blue component of the pixel color). The 
other two channels hold corresponding information for the green and red components of the pixel color. The three 
components are used to index the red green and blue parts of the lookup table. The RGB components from the lookup 
table are combined to produce a pixel with a particular hue and intensity. 

Figure 1 XBGR Layout 

31 24 23 16 15 87 0 

unused blue component green component red component 

The op Argument 

The standard rop operations are allowed, to a limited extent, between pixrects of different depths. The table below 
sums up the limitations: 
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The value n can be the values 1,8, and 32 bits. Note that 8 to 32 and 32 to 8 are not supported. To translate pixel 
colors between 8 and 32, you must use the formula shown below. It uses the 8-bit pixel value (the variable colorS), in 
conjunction with the 8-bit colormap, to generate a 24-bit color (saved in the integer variable color24). The color24 
variable now has its true color stored in XBGR format. The value can then be saved as a 32-bit pixel, in the pixrect 
P IXPG_2 4 BIT_C0L0R planegroup. 


- ' 

int color24; 

unsigned char red[256],green[256],blue[256]; 

color24 * red[color8] + green[colorS] « 8 + blue[color8] « 16; 

V_> 


The color field of the op argument, used in many pixrect functions, is interpreted differently on the cg8 frame 
buffer. The most significant 8 bits of this field (bit 24 to 31 of op) is the value of the blue channel, the next 8 bits 
(bit 16 to 23) is the value of the green channel and the next 8 bits (bit 8 to bit 15) is the value of the red channel. 


Figure 2 op fields 
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The Pixrect library cannot distinguish between indexed 8-bit color and 24-bit direct color applications. Do iwt expect 
your current 8-bit color programs to use 24-bit color without modification. 

24 vs 32 bits 

Since true color pixrects use only 24 bits per pixel to encode color information, yet are stored and handled as 32-bit 
entities, a number of compatibility issues come up. 


Memory Pixrects 

It is possible to create 24-bit memory pixrects. This may be useful for synthesizing images that are later displayed. 
24-bit-to-24-bit operations are supported; you cannot, however, perform a rop operation between a 24-bit pixrect 
and a 32-bit one, even if the 32-bit pixrect is in XBGR format. 

Sometimes, it is more efficient to use a 24-bit memory pixrect to generate an image, then save it as a 24-bit raster file. 
When pr_load () is called to load a 24-bit raster file, however, it automatically loads it in as a 32-bit pixrect so that 
pixrect operations run more efficiently. When pr_save () is called, the converted pixrect will be saved in a 32-bit 
raster file. 
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Run-Length Encoding 

It makes little sense to save a 32-bit pixrect (in XBGR format) as a run-length encoded raster file, although there is no 
technical difficulties doing so. Since it is a true-color pixrect, it is unlikely any adjacent bytes have the same value, 
even if the adjacent XBGR pixels do. The run-length encoding compression scheme is byte-oriented, not pixel- 
oriented, so it is not likely to reduce the size of the file. 

Plane Groups 

Pixrect has added a new plane group, PIXPG_2 4BIT_C0L0R, for access to the cg8 24-bit buffer. The new plane 
group provides 24-bit RGB (red green blue) values stored in XBGR format in 32-bit pixels. All the normal logical 
operations and plane masking are available; many of the logical operations are not useful with color, however. 

The cg8 also has an overlay and an enable plane, providing three planegroups for cg8 pixrects; 


Table 1 eg 8 planegroups 


Plane 

Function 

PIXPG_OVERLAY 

P IXPG_OVERLAY_ENABLE 
PIXPG_24BIT_COLOR 

Window System Plane 
Enable Plane 

24-bit Color Plane 


The overlay plane is black and white by default. It does, however, have its own 2-bit colormap. The foreground and 
background colors of the overlay plane can be set using the pr_putcolormap () command with the overlay plane 
as the pixrect argument. The colormap contains two 24-bit color values; one for pixels set to 1, and one for pixels set 
to 0. 

The enable and overlay planes have the same behavior seen in previous Sun frame buffers (cg4); the enable plane 
mediates between the overlay and the 24-bit plane. When an enable pixel is one, only the overlay plane is visible; 
when it is zero, only the 24-bit plane is visible. 


Figure 3 eg8 planegroups 
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NOTE: The default plane for the cg8 is the overlay plane, not the 24-bit plane. 

The example code below shows how to test whether the color board the application is using supports 24-bit color. 

This type of code is important for writing software that can run with both 8-bit or 24-bit color. 
- 

#include <pixrect/pixrect__hs. h> 
char maxgroup[PIXPG_24BIT_COLOR + 1]; 

pr_available_j)lane___groups (pr^ PIXPG_24BIT_COLOR + 1,\ 

maxgroup); 

if (maxgroup[PIXPG_24BIT_COLOR] != 0) 

printf("Board supports 24~bit color\n"); 

^ _ > 


Lookup Tables 

The cg8 has three lookup tables that can be used to adjust the intensity response of each component (red, green, 
and blue) of the 24-bit color values. These tables can be used to make the color response nonlinear (for example in 
gamma correction), or for special color effects. 

For each color component, the intensity value of the pixel is used as an index to the corresponding table entry. 

The value of that entry is then used as the actual intensity component for the displayed pixel. This can be used to 
compensate for color inaccuracies generated by the display hardware; thus by applying color correction techniques 
(like gamma correction) with the lookup table, the displayed image approaches tme color. 

Both 24-bit color lookup tables and 8-bit color colormaps require 768 bytes of space. The Pixrect functions 
pr_get colormap () and pr_put colormap () commands are used to read or modify 8-bit colormaps, while 
pr_get lut () and pr_put lut () are the corresponding commands to read and modify 24-bit lookup tables. 


msun 
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Using the pr_j>ut lut () macro to load the lookup tables is similar to using the pr_putcolormap () function; 
the red[], green[], and blue[] array arguments correspond to the appropriate lookup tables. In the same way, 
pr_getlut {) loads these same arrays from the lookup tables. 

Upon opening a pixrect, the cg8 lookup table is loaded with linear ramps from 0 to 255 for the red, green, and blue 
tables. The default table therefore has no built-in corrections. All applications share the same lookup table; you can¬ 
not divide it up into portions as you can with 8-bit colormaps, and lookup table segmenting is not allowed in Pixrect 
or SunViewl running on a cg8. 

The lookup table segment size is fixed at 256; no lookup segmenting is allowed. 


Two pixrect lookup macros, pr_putlut () and pr_getlut () are shown below: 
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The PR_FORCE_UPDATE value in the pr_putlut () macro is necessary because there is no colormap sharing in 
Pixrect. The sample program below shows the macros in use: 


— 


tinclude <pixrect/pixrect_hs.h> 


pr = pr_open(”/dev/cgeight0”); 

pr_set__plane___group (pr, PIXPG_2 4BIT_COLOR) ; change to 24-bit plane 
pr_getlut(pr, 0, 256, red, green, blue); 
gainma_correct (red, green, blue) ; a user-supplied function... 


pr_putlut(pr, 0, 256, red, green, blue); 



The code fragment above opens the cg8 frame buffer, and changes the current plane group to be 24-bit color (the 
default is the overlay plane). The pr_put lut () and pr_getlut () macros read, then reload the lookup tables. 

Indexed 24-bit Color 

At this time, indexed 24-bit color (the 24-bit equivalent to 8-bit color) is not supported in Pixrects or SunViewl. 

SunViewl 

The 24-bit SunView 1 model is less general than the 8-bit one. SunView 1 on the cg8 is a monochrome desktop 
residing in the overlay plane. The color canvases in the desktop are 24-bit color, all affected by the same lookup 
table. 

Overlay Colormap 

Although the SunView 1 desktop is restricted to two colors (normally black and white) there is a 2 bit colormap for 
the overlay plane. This means the programmer can set the foreground and background colors of the desktop by using 
the pw_putcolormap () command with the overlay plane as the pixrect argument. The table contains two 24-bit 
color values; one for pixels set to 1, and one for pixels set to 0. 

Modifying the Lookup Table 

There is no lookup table sharing implemented in the 24-bit SunView 1 system. Any changes in the lookup table affect 
all systems. SunViewl cannot modify the lookup table directly. The pw_putcolormap () command is ignored 
when accessing the lookup table. There is no pw_put lut () macro corresponding to the Pixrect pr_putlut ( ) 
macro. To change the lookup table, the SunView 1 application must make a pr_put lut () caU with Pixrect. To do 
this, the application must extract the pixrect pointer from the pixwin data structure, then use that pointer in a 
pr_put lut () call. An example code fragment that performs gamma correction is shown below. We assume the 
user has written a function called gamma_correct () which adjusts the red, green and blue values of the lookup 
table. 

^ _ ___ ^ 
unsigned char red[256], green[256], blue[256]; 

pr_set_plane_group(pw->pw_pixrect, PIXPG_24BIT_COLOR); 
if (pr_get__plane_group (pw->pw__pixrect) != PIXPG_24BIT_COLOR) 
return (0); 

pr__getlut (pw->pw__pixrect, 0, 255, red, green, blue); 
gamma_correct(red, green, blue); 

pr_putlut(pw->pw_pixrect, 0, 255, red, green, blue); 

--- - . . - . .. 
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This example uses the pixwin from the window canvas, extracts the pixrect, and switches to the 24-bit planegroup. If 
the planegroup is not PIXPG_24BIT_C0L0R, then the display device does not support 24-bit color, and the rest of 
the program is aborted. If it does have true color, the code uses pr_get lut () with the extracted pixrect to get the 
contents of the lookup table, uses gainma_correct ( ) to adjust the values, then calls pr_put lut ( ), to alter the 
lookup table. 

See the Pixrect example code near the end of this section for more details in using pr_put lut () and 
pr_getlut(). 

All pw_putcolormap () and pw_getcolormap () calls arc ignored when the call is accessing a 24-bit plane- 
group. No error is reported. This allows older 8-bit color applications to fail ‘ ‘gracefully’ ’ when run on the cg8. 

SunViewl Startup 

When starting a SunViewl desktop on a cg8 device, only 24-bit true color is allowed. Thus the following SunViewl 
flags are disabled: 


Figure 5 Disabled SunViewl Flags 

sunview -8bit_color_only 
-overlay_only 
-toggle_enable 


The 24-bit Canvas 

The basic sunview window requirement is to set the CANVAS_COLOR2 4 attribute to TRUE. This tells 
the window system that this will be a true color window. The window canvas will then reside in the cg8 
PIXPG_24BIT_C0L0R plane group. The initial lookup table segment is CMS_COLOR_lDENTITY. 

Using CANVAS_COLOR24 runs the window canvas in the 24-bit frame, and using CANVAS_FAST_MONO puts the 
canvas in the overlay plane. If both attributes are set, the one most recently set takes effect. 

All 24-bit canvases use the same lookup table; any change to this table will affect all canvases running on the eg 8. 
The backing pixrect for 24-bit canvases will be 32 bits deep, storing the pixels in the XBGR format described earlier. 

Any windows not designated as 24-bit canvases will be monochrome, using the colormap of the overlay plane. 


Porting from 8-bit color to 24-bit color 

Eight bit Color applications must be modified if they are to work properly on the cg8. Since 8-bit color uses a color- 
map, while 24-bit color uses a lookup table, the color values generated by the program should be translated using the 
following formula: 

- \ 

int color24; 

unsigned char red[256],green[256],blue[256] ; 

color24 = red[color8] + green[colorS] « 8 + blue[color8] « 16; 

V_> 


The colors variable is the 8 bit pixel value to be translated. The red[], green[], and blue[] arrays are the contents of 
the colormap used with the 8-bit pixels being translated. The color24 variable holds the resulting 24-bit color in 
XGBR format. This value can be loaded into a 32-bit pixel, in the pixrect PIXPG_24BIT_C0L0R planegroup. 



Revision A of 24 April 1989 



Documentation Errata for SunOS Release 4.0.3 9 


Basically, this formula translates the 8-bit index into the red, green and blue components that would be displayed 
on the screen of an 8-bit color system. These translated color components are then loaded into the appropriate bit 
locations for a 24-bit color value in XGBR format. 

Porting Limitations 

While the translation approach is probably the fastest way make 8-bit color applications portable to 24 bits, it is not 
the best. First, you are not taking advantage of all the additional colors available on the cg8. More importantly, the 
24-bit system is going to be slower by about a factor of four (moving 32-bit, instead of 8-bit, pixels). Adding an 
additional translation step will slow it down further. 

It would be better to change the application model so it understands 24-bit color in the first place. It could be set to 
cut down its 24-bit colors to 8 when it runs on 8-bit color boards (for portability). 


Diagnostics 

The two sections below describe the diagnostics available for the eg8 frame buffer. 

Boot PROMs 

The cg8 is the first frame buffer to utilize an external boot PROM. The external boot PROM allows all frame buffer 
specific code to placed in its own the frame buffer PROM. This allows the host machine to test the frame buffer 
without knowing its configurations details. 

The boot sequence has been changed to accommodate tlie new boot code. At boot up, host machine self-tests are mn 
nonnally, but the frame buffer selftests are no longer part of the host’s PROM. 

Once the host machine performs its own self-test, the host CPU probes all external devices for external boot PROMs. 
When it finds a frame buffer, it loads the frame buffer code into its own memory. After the code is loaded, the host 
CPU initializes all frame buffer data, such as manufacturer, model number, revision, and resolution, then moves the 
information into an area accessible to the operating system. The host machine then initializes the display routines. 

At this point, the frame buffer self-tests are executed. The table below shows the tests that are executed, along with 
their frame buffer status codes. 

NOTE The DM notation indicates this test is only run if the diagnostic mode switch is enabled. 
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Table 2 Frame buffer codes 


08 

Enable memory tests. 


08 

Quick address line test. 


09 

Quick data line test. 


OA 

Long address pattern test. 

DM 

OB 

Data size test. 

DM 

oc 

Data bits test. 

DM 

OD-OF 

Reserved for future expansion. 


1 

Overlay memory tests. 


1 

Quick address line test. 


1 

Quick data line test. 


1 

Long address pattern test. 

DM 

1 

Data size test. 

DM 

1 

Data bits test. 

DM 

15-1 

Reserved for future expansion. 


1 

Color memory tests. 


1 

Quick address line test. 


1 

Quick data line test. 


lA 

Long address pattern test. 

DM 

IB 

Data size test. 

DM 

1C 

Data bits test. 

DM 

10-lF 

Reserved for future expansion 


2 

Color controller ( ramdac test). 


2 

Color palette tests. 


29-3F 

Reserved for future expansion. 


40-FF 

Reserved for future expansion. 
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The following is the output from the selftests while the diagnostic switch is in the diag position: 

—--- 

sizing Memory (size = 0x00000008 Megabytes). 

Selftest Completed. 

Type a key within 10 secondsto enter Extended Test System (e for echo mode). 

Looking for display devices 
cgeight 

Testing display 
Testing cgeight 
Overlay-plane 
Data lines test 
Address quick test 
Data size test 
Data bits test 
Address=data test 
Enable-plane 

Data lines test 
Address quick test 
Data size test 
Data bits test 
Address=data test 

V_> 


Sysdiag 

The cg8 is tested in sysdiag by a test called color 2 4. This test verifies all device-specific driver routines, 
colormaps, and frame buffer memories. Since all tests in sysdiag are executed automatically, no user intervention 
is required to run color24. 
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Pixrect Example Code 

As the number of bits per pixel increases, the amount of data stored in a pixrect becomes significant. The size of a 
XGBR-format pixrect is substantial; thus, both space efticicncy and performance become issues. The program below 
shows a way to minimize space consumption and maximize performance when loading true-color pixrects; 



/* 

* A program which loads images to the cg8 frame buffer using both pixrect 

* and mmap. pr_load() is not used, it consumes too much memory resources. 

* We actually open the image file, mmap it into user's addressing space 

* and access it directly. 

*/ 

/* 

* This program is practically: 

* file_pixrect = pr_load(file); 

* pr_rop (screen, . . . ., f ile__pixrect, . . .) ; 

* only fancier. 

*/ 

#include <stdio.h> 

#include <sys/types.h> 

#include <sys/mman.h> 

#include <sys/stat.h> 

#include <pixrect/pixrect_hs.h> 

Pixrect *pr_cg8; 

main (argc, argv) 
int 
char 

{ 

char 
FILE 

struct stat 
char 
char 
u_char 

prog = *argv+4-; 

if ( (pr_cg8 = pr__open ("/dev/cgeightO") ) == NULL || 

(pr_cg8 = pr_open ("/dev/fb")) == NULL) { 

fprintf (stderr, "%s: fail to open cgeightO or fbO, prog); 
return 1; 

} 

pr_available_plane_groups (pr_cg8, PIXPG__24BIT_COLOR + 1, groups); 
if ( ’.groups [PIXPG_2 4BIT_COLOR] ) { 

fprintf (stderr, ”%s: Not a 24-bit framebufferO, prog); 
return 1; 

} 

V ___/ 

sun 

microsystems 



argc; 
*argv[] ; 


*fname; 

*fp; 

St ; 

*prog; 

groups [PIXPG__24BIT_COLOR + 1] ; 
*fptr; /* file pointer 
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while (—argc > 0 && *argv != NULL) { 
fname = *argv++; 
if (fname && 

(strlen (fname) <= 0 I I (fp = fopen (fname, ”r*’)) == NULL)) { 
pr_close (pr_cg8); 

fprintf (stderr, ”%s: fail to open %s0, prog, fname); 
continue; 

) 

if (fstat (fileno (fp), &st) < 0 || 

(fptr = (u_char *) mmap (0, st.st__size, 

PROT__READ, MAP_SHARED, fileno (fp) , 0)) ==NULL) { 
fprintf (stderr, "%s: fail to map %s0, prog, fname); 
fclose (fp); 
continue; 

} 

im__load (fptr) ; 

munmap (fptr, st.st_size); 

fclose (fp); 

} 

pr_close (pr_cg8); 
return; 


/* loading image from file */ 
im_load (fptr) 

u_char *fptr; 

{ 

struct rasterfile *rh; 
struct pr_pos off; 

rh = (struct rasterfile *) fptr; 
fptr += sizeof (struct rasterfile);/* Iseek */ 
off.x = (pr_cg8“>pr_size.X - rh~>ras_width) / 2; 
off.y = (pr_cg8->pr_size .y - rh->ras__height) / 2; 

if (rh“>ras_magic == RAS_MAGIC) { 

switch (rh->ras_depth) { 

case 32: 

case 24: 

case 8: 

load___32 (rh, off, fptr) ; 
break; 
case 1: 

load_l (rh, off, fptr); 
break; 
default: 
break; 


static 

load__32 (rh, off, fptr) 


^ sun 
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struct rasterfile *rh; 
struct pr_pos off; 
u_char *fptr; 


{ 


u_char 


*r, 

^b; 

int 


maplen; 

register 

int 

linesize; 

register 

int 

fb__increment; 

int 


if 

jf 

pixel^size; 

register 

u_char 

• *im buffer; 

union fbunit 

*fb_image; 

union fbunit 

*fb__ptr; 


/* 

* Clear the overlay and enable plane. Black out the frame buffer and 

* open the hole on the enable plane to let the frame buffer "see thru". 
*/ 

pr__set_plane_group (pr_cg8/ PIXPG__OVERLAY) ; 

pr_rop (pr_cg8^ 0, 0^ pr_cg8“>pr_size.x, pr_cg8“>pr_size. 

PIX_SRC I PIX__COLOR (1), 0, 0, 0); 
pr_set_plane__group (pr_cg8^ PIXPG_OVERLAY_ENABLE) ; 
pr___rop (pr_cg8, 0^ 0, pr_cg8->pr__size.pr_cg8~>pr_size.y^ 

PIX_SRC I PIX_COLOR (1), 0, 0, 0) ; 
pr_set_plane_group (pr_cg8^ PIXPG_24BIT_COLOR) ; 
pr_rop (pr_cg8, 0^ 0^ pr_cg8“>pr_size. x^ pr_cg8->pr_size .y^ 

PIX_SRC, 0, 0, 0); 

pr_set__plane_group (pr__cg8, PIXPG_OVERLAY_ENABLE) ; 

pr_rop (pr__cg8^ off.x, off.y^. rh->ras_width^ rh“>ras_height, 

PIX__SRC, 0, 0, 0); 


/* ready to show the image */ 

pr_set__plane_group (pr_cg8, PIXPG_24BIT_COLOR) ; 

if (rh->ras_maptype == RMT_EQUAL_RGB) { 

maplen = rh->ras_maplength / 3; 

r = (u__char *) fptr; 

fptr += maplen; 

g = (u__char *) fptr; 

fptr += maplen; 

b = (u_char *) fptr; 

fptr += maplen; 

if (rh->ras_depth != 8) 

pr_jDutlut (pr_cg8, 0^ maplen, r, g, b) ; 

} 


/* 

* Get the pointer to the frame buffer, offset it to the right starting 

* pixel. 
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fb_image = (union fbunit *) mprp^d (pr_cg8)->mpr .md__image; 
pixel__size = rh->ras___depth / 8/ /* amount to increment the file 

* pointer */ 

linesize = mpr__linebytes (rh->ras_width, rh“>ras__depth) ; 

fb_increment = mprp_d (pr_cg8)->mpr.md_linebytes / sizeof (union fbunit); 
if (off.y >= 0) 
fb_image += off.y * 

(mprp___d (pr_cg8)->mpr .md_linebytes / sizeof (union fbunit)); 

else 

fptr -= off.y * linesize; 
if (off.x >= 0) 
fb_image += off.x; 
else 

fptr -= pixel__size * off.x; 

for (j = 0; j < rh->ras_height && j < pr_cg8~>pr_size.y; 

j++, fptr += linesize^ fb_image += fb__increment) { 

im__buffer = fptr; 
fb_j5tr = fb_image; 

for (i = 0; i < rh->ras__width && i < pr__cg8->pr_size.x; 
i++^ im_buffer += pixel_size^ fb__ptr++) { 
switch (rh->ras__depth) { 
case 32: 

fb_j:>tr->packed = ((union fbunit *) im___buf fer)->packed; 

break; 

case 24:{ 

union fbunit store; 

store .channel .B = im__buffer [0 In¬ 
store . channel. G = im_buffer[1] ; 
store.channel.R = im_buffer[2]; 
fb_jptr-->packed = store .packed; 
break; 

} 

case 8:{ 

union fbunit store; 

store . channel. R = r[*im__buffer]; 
store.channel.G = g[*im_buffer]; 
store, channel. B = b [ *im__buf f er] ; 
fb_ptr->packed = store.packed; 

} 

} 

} 

} 

} 


#define SMALLER(src, dst^ w) \ 

(src->pr_size.w < dst->pr_size.w ? src~>pr_size.w : dst“>pr_size.w) 
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static 

load__l (rh^ off, fptr) 

struct rasterfile *rh; 
struct pr__j>os off; 
u_char *fptr/ 

{ 


Pixrect *mono; 

struct pr__pos dup; 

struct prj>os small; 


pr_set_plane_group (pr__cg8, PIXPG_OVERLAY) ; 

pr_rop (pr_cg8, 0, 0, pr__cg8->pr__size. x, pr_cg8->pr_size .y, 

PIX__SRC I PIX_COLOR (1), 0, 0, 0); 
fptr += rh->ras_maplength; 

mono = mem__point (rh~>ras_width, rh->ras_height, rh->ras_depth, (short *) 
fptr); 

dup.x = dup.y = 0; 

if (off.x < 0) 

dup.x = -off.x, off.x = 0; 

if (off.y < 0) 

dup.y = -off.y, off.y = 0; 

pr_set__plane__group (pr__cg8, PIXPG_OVERLAY_ENABLE) ; 
pr__rop (pr__cg8, off.x, off.y, 

SMALLER (mono, pr_cg8, x) , 

SMALLER (mono, pr__cg8, y) , 

PIX__SRC I PIX_COLOR (1), 0, 0, 0); 
pr__set_j)lane_group (pr_cg8, PIXPG_OVERLAY) ; 
small.X = SMALLER (mono, pr_cg8, x); 
small.y = SMALLER (mono, pr_cg8, y); 
pr_rop (pr_cg8, off.x, off.y, 
small.X, small.y, 

PIX_SRC, mono, dup.x, dup.y); 
pr___destroy (mono) ; 
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SunView Example Code 


* This sample Sunview program shows how to use rops^ vectors and pixels, 
*/ 

#include <stdio.h> 

#include <suntool/sunview.h> 

#include <suntool/canvas.h> 


Frame 

Canvas 

Pixwin 


f r ame ; 
canvas; 
*'pwin; 


/* Base frame. */ 


frame = window__create (NULL^ FRAME, 

FRAME__LABE L, a rgv [ 0 ] , 

F RAME_ARGC_P T R_ARGV, &argc, argv, 

0 ) ; 

if (frame == NULL) { 

fprintf (stderr, ”%s: Failed to create frame.0, argv[0]); 
exit (1); 

} 

/* Open the canvas. */ 

canvas = window_create (frame, CANVAS, 

CANVAS_RETAINED, FALSE, 
CANVAS_REPAINT__PROC, repaint__canvas, 
CANVAS_COLOR2 4, TRUE, 

0 ) ; 

if (canvas == NULL) { 

fprintf (stderr, ”%s: Failed to create canvas. 0, argv[0]); 
exit (1); 

) 

/* Get the pixwin associated with this canvas. */ 
pwin = (Pixwin *) window_get (canvas, WIN_PIXWIN); 
if (pwin == NULL) { 

fprintf (stderr, ”%s: Failed to get pixwin.0, argv[0]); 
exit (1); 

} 

window_main_loop (frame); 


Asun 
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void 

repaint_canvas () 
{ 

int 

int 


i; 

offset = 200; 


/* Loop index. */ 

/* To move ramps toward center of */ 
/* window. */ 


/* Rop a white block (proves that r^ g and b work). */ 

pw_rop (pwin, 0, 0, 100, 100, (PIX_SRC I PIX__COLOR (OxOOffffff) ) , 0, 0, 0) ; 


/* Draw some ramps in different colors 
for (i =0; i < 256; i++) { 

pw__vector (pwin, 
pw__vector (pwin, 
pw_vector (pwin, 

} 




i 

+ 

offset. 

100, 

i 

+ 

offset. 

110, 

PIX_ 

_SRC, 

(i 

« 

0)) ; 

i 

+ 

offset. 

112, 

i 

+ 

offset. 

120, 

PIX_ 

SRC, 

(i 

« 

8)); 

i 


offset. 

122, 

i 

+ 

offset. 

130, 

PIX__ 

SRC, 

(i 

« 

16)) ; 


/* Spit 

out some pixels 

so we know that 

they work. */ 

pw_put 

(pwin. 

500, 

500, 

OxOOffOOOO); 

/* 

red */ 

pw__put 

(pwin. 

500, 

501, 

OxOOffOOOO); 



pw_put 

(pwin. 

500, 

502, 

OxOOffOOOO); 



pw_jput 

(pwin. 

501, 

500, 

OxOOffOOOO); 



pw__put 

(pwin. 

501, 

501, 

OxOOffOOOO); 



pw_put 

(pwin. 

501, 

502, 

OxOOffOOOO); 



pw_put 

(pwin. 

504, 

500, 

OxOOOOffOO); 

/* 

green */ 

pw__put 

(pwin. 

504, 

501, 

OxOOOOffOO); 



pw_put 

(pwin. 

504, 

502, 

OxOOOOffOO); 



pW_J)Ut 

(pwin. 

505, 

500, 

OxOOOOffOO); 



pw_put 

(pwin. 

505, 

501, 

OxOOOOffOO); 



pw_put 

(pwin. 

505, 

502, 

OxOOOOffOO); 



pW__J5Ut 

(pwin. 

508, 

500, 

OxOOOOOOff); 

/* 

blue */ 

pw_put 

(pwin. 

508, 

501, 

OxOOOOOOff); 



pw_put 

(pwin. 

508, 

502, 

OxOOOOOOff); 



pw_put 

(pwin. 

509, 

500, 

OxOOOOOOff); 



pw_put 

(pwin. 

509, 

501, 

OxOOOOOOff); 



pw_put 

(pwin. 

509, 

502, 

OxOOOOOOff); 
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Suii-2 and Sun-3 Assembler 

This section describes changes to the Assembly Language Reference, Part Number 800-1773, that supports the 
MC68030 processor included in SunOS release 4.0.3 as assembler for the Sun-2 and Sun-3 workstations. 

For more information about the MC68030, see the MC68030 Enhanced 32-Bit Microprocessor User’s Manual, 
Motorola Inc. document MC68030UM/AD, or later. 


New Control Register Support 

The MC68030 has six control registers not included in the MC68020 or MC68010. The registers are named crp, 
srp, tc, ttO, ttl, and psr. 

Replace the table on page 43 of the Assembly Language Reference with this table containing the new register names: 


Name 

Register 

sp 

the stack pointer, which is equivalent to a 7 

sr 

the status register 

cc 

the condition codes of the status register 

usp 

the user mode stack pointer 

pc 

the program counter 

sf c 

the source function code register 

dfc 

the destination function code register 

fpcr 

the floating-point control register 

fpsr 

the floating-point status register 

fpiar 

the floating-point instruction address register 

crp 

64-bit CPU root pointer 

srp 

64-bit supervisor root pointer 

tc 

32-bit translation control register 

tto 

32-bit transparent translation register 

ttl 

32-bit transparent translation register 

psr 

MMU status register 


New Processor Instruction Support 

The new MC68030 instructions supported by the SunOS Release 4.0.3 as are: pf lush, pload, pmove, ptest, 
and their variants. Note that all the new instructions are privileged. 

The following table lists the instructions specific to the MC68030 as supported by as. Append it to the end of 
Table B-1 starting on page 60 in the Assembly Language Reference. 

NOTE as has no explicit - 030 flag: the new instructions are always recognized and assembled. Obviously, this 
would create problems with code run on non-MC68030 machines. 
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Table 3 List of MC68030 Instruction Codes 


Mnemonic 

Operation Name 

Syntax 

Processor 

pflusha 

flush all ATC entries 

pflusha 

MC68030 

pflush 

flush ATC entry 

pflush Mata, Mata 

MC68030 



pflush dn,Mata 

MC68030 



pflush dn,Mata,ea 

MC68030 



pflush sto,Mata 

MC68030 



pflush sfc,Mata,ea 

MC68030 



pflush dfc,Mata, axQ {Q,dl :1) 

MC68030 



pflush dfc,Mata,axQ 

MC68030 

ploadr 

load ATC entry 

ploadr Mata,2il 

MC68030 



ploadr dw,ar@(8) 

MC68030 



ploadr sfc, ax@(8,d7:1) 

MC68030 



ploadr dfc,cLr@ 

MC68030 

ploadw 


ploadw Mata, 2 : 1 

MC68030 



ploadw dn,ar@(8) 

MC68030 



ploadw sfc, ax@(8,d7:1) 

MC68030 



ploadw dfc,ar@ 

MC68030 

pmove 

move to/from MMU registers 

pmove crp,ar@ 

MC68030 



pmove srp,ar@ 

MC68030 



pmove tc,ar@ 

MC68030 



pmove psr,ax:@ 

MC68030 



pmove tt0,ajc@ 

MC68030 



pmove ttl,ax@ 

MC68030 



pmove ar@, crp 

MC68030 



pmove ax@,srp 

MC68030 



pmove ajc@,tc 

MC68030 



pmove ax@,psr 

MC68030 



pmove ar@,tt0 

MC68030 



pmove ar@,ttl 

MC68030 

ptestr 

test logical address 

ptestr Mata,2:1,Mata 

MC68030 



ptestr dn, ax(^ (S) ,^data 

MC68030 



ptestr sf c, ax^ {Q, dl: 1) ,Mata, a3 

MC68030 



ptestr df c, axi^ ,Mata, a 

MC68030 

ptestw 


ptestw ^data, 2 : l,Mata 

MC68030 



ptestw dn, axQ {S) ,Mata 

MC68030 



ptestw sf c, ax^ {8 ,dl :1) ,Mata, a3 

MC68030 



ptestw df c, ax^ ,Mata, atl 

MC68030 

pmoveflush 

move to/from MMU register. 

pmoveflush crp,ar@ 

MC68030 


flush ATC 

pmovef lush srp,ajc@ 

MC68030 



pmoveflush tc,ar@ 

MC68030 



pmoveflush psr,ar@ 

MC68030 



pmoveflush tt0,ajc@ 

MC68030 



pmovef lush ttl,ax:@ 

MC68030 
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Table 3 List of MC68030 Instruction Codes — Continued 


Mnemonic 

Operation Name 

Syntax 

Processor 



pmoveflush ax@,crp 

MC68030 



pmoveflush ajc@, srp 

MC68030 



pmoveflush ax@,tc 

MC68030 



pmoveflush axQ^psr 

MC68030 



pmoveflush a;c@,tt0 

MC68030 



pmoveflush aJC@,ttl 

MC68030 
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Device Drivers 

This section corrects portions of Writing Device Drivers , Part Number 800-1780-10, for SunOS Release 4.0,4.0.1, 

and 4.0.3. 

rmalloc () Pages 35 (bottom) and 377 refer to rmalloc () and iopbmap. The statement “this will 

get a small block of memory back from the beginning of DVMA space” does not describe 
how this space is accessed. 

The iopbmap is a byte-aligned table. The address it returns is not aligned on a long word 
boundary. If a non-aligned address is accessed, a panic may result. CaUers of rmalloc () 
should ask for a few bytes of memory more than they need, and round up the address to a full 
word boundary if necessary. This applies to both Sun-3’s and Sun-4’s, but it is more critical 
to Sun-4’s, since they can only address using full word alignment. 

Sun386i Interrupt On the bottom of page 352 and the top of page 353, it states that xxintr () receives by 

default the unit number of the device that interrupted it, or something else by changing the 
value in md_intr->v_vptr. 

This does not apply to the Sun386i. The Sun386i receives two arguments. The first is the 
current priority level (cpl) and the second is the interrupt request (irq). The irq is 
hardwired so it cannot be changed. The intermpt routine can never receive the unit number. 
The unit number can be obtained by saving the interrupt request channel (board level + 8) at 
attach time and then figure out which device received the interrupt at interrupt time. 

tty_std(4M) On page 164, in Figure 9-2, the names in the left column: tty_compat. 4m, 

tty_std. 4m, and nit . 4m are System V names. These names are now ttcompat. 4m, 
Idterm. 4m, and nit . 4p respectively. These same changes should also be made on pages 
311 and 312. 

edevsw On the bottom of page 45, the edevsw structure is listed with each element. The two 

elements d_stop and d_tt ys no longer exist in SunOS and should not be in the table. 

kmem_alloc On page 369, the kmem_alloc () description says the routine calls panic () if its request 

cannot be satisfied. This was true in SunOS 3.X, but not for SunOS 4.0 and above. In 
SunOS 4.0 and above, NULL pointer is returned if the space cannot be allocated. 

skioctl On the bottom of page 142 the elements of the edevsw are described. There are two 

routines shown that are no longer used. References to xxstop {) and “a tty structure 
pointer” should not be there. See edevsw explanation above. The description of the 
edevsw entries in the box on page 142 should also be changed to reflect the new order. 

The three lines that say 

skopen, skclose, skread, skwrite, 
nodev, nodev, nodev, 0, 
seltrue, skmmap 

should occur in the following order. References to the ioctl routine should include the 
code from page 135 in the previous chapter, and references to the select routine should 
include the code from page 132. The new list should be; 
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selwait 


Ramdisk 


Ramdisk node 


strlog() 

tty structures 


tty structure 


cdevsw structure 


skopen, skclose, skread, skwrite, 
skioctl, nodev, skselect, skmmap 


On pages 133 and 134, there are references to selwait () making it look like it is a func¬ 
tion. Selwait is an integer, so there should be no parenthesis. This reference is at the top 
and bottom of page 133 and the top of page 134. In addition, the index references on page 
449 and 451 should not have parenthesis. 

Chapter 8 (pages 151 -156) describes how to implement a ramdisk pseudo-device driver. 
This example is based on SunOS 3.5 and does not work on SunOS 4.0. If this program is mn 
under SunOS 4.0 it may cause your system to crash. 

In the box on page 154 is a list of functions for the cdevsw. As described in the cdevsw 
section above, this list should have two less entries. The list should look like this; 

ramopen, nulldev^ ramread^ ramwrite, 
nodev^ nulldev^ seltrue^ nodev 

On page 154 the mknod example references ramOc as the device name. The correct 
command should be: 

/etc/mknod ramO b 8 0 
/etc/mknod rramO c 30 0 

On the top of page 155 the reference to device name /dev/ramOc should instead be 
/ dev/ramO. 

On page 337 is a description of the routine strlog (). Although this appears in the manual, 
it is not a Sun-supported routine and is not recommended to use. 

In Chapter 3 on page 45, at the end of the second paragraph, the statement “For terminals, 
the cdevsw structure also contains a pointer to an array of tty structures associated with 
the driver.” should be deleted. 

In Chapter 3 on the top of page 46, the first paragraph “Only teletype-like devices (such as 
the the console driver, the mti driver, and the zs driver) use the tty structure. All other 
devices set it to zero.” should be deleted. 

In Chapter 3 on page 46, the first box shows the cdevsw structure. Some of the names have 
been changed. The original routines are; 

egoneopen, cgoneclose, nodev, nodev, /*14*/ 

cgoneioctl^ nodev, nodev, 0, 
seltrue, egonemmap, 

which should be changed to; 

egoneopen, cgoneclose, nodev, nodev, /*14*/ 

cgoneioctl, nodev, seltrue, egonemmap, 

0, spec___segmap. 
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md_driver 

kernel 

header file 


uio .h 

conf. c 

ram. c 


In Chapter 3 on page 52, the last word on the page “definition” should be “declaration.” 

In Chapter 4 on page 63, the statement ‘ ‘kernel is monolithic monitor type of operating 
system” should have the word “a” inserted resulting in “kernel is a monolithic monitor type 
of operating system” 

In Chapter 6 on page 114, the box has a series of include statements. They should be 
changed from 

#include ”../h/param.h" 

#include "../h/buf.h" 

#include ”../h/file.h” 

#include ” . . /h/dir . h** 

#include ”../h/user.h” 

#include ”../h/uio.h” 

#include ”../machine/psl.h" 

#include ”../sundev/mbvar.h” 

to 

#include <sys/param.h> 

#include <sys/buf.h> 

#include <sys/file.h> 

#include <sys/dir.h> 

#include <sys/user.h> 

#include <sys/uio.h> 

#include <machine/psl.h> 
tinclude <sundev/mbvar.h> 


In Chapter 6 on page 120, the last paragraph makes reference to an include file as 
/usr/include/sys/uio . h which should be changed to <sys/uio. h>. 

In Chapter 7 on page 139, the first square item states that conf . c is “a C-language source- 
code file which contains the definitions of the switches”. Definitions should really be 
changed to “a C-language source-code file which contains the default initializations of the 
switches” 


In Chapter 8 on page 152, the box contains include statements for the driver. 
These statements should be changed from: 


tinclude ”../h/param.h” 
tinclude ”../h/errno.h" 
tinclude ”../h/uio.h” 
tinclude . . /h/buf . h” 


to: 


tinclude 

tinclude 

tinclude 

tinclude 


<sys/param.h> 
<sys/errno.h> 
<sys/uio.h> 
<sys/buf.h> 


IIncludes *\.lhltypes.h” */ 


/'^Includes <sysltypes.h> */ 
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alternatives 


putctll 


testb 


boottime 


QUEUE 


In Chapter 9 on page 191, the end of the second paragraph states" ‘ ‘ interfaces to the two the 
non-802.2 drivers and the IP multiplexor.”. There is an extra “the” that should be deleted, 
making “the two non-802.2 drivers and the IP multiplexor.”. 

In Appendix A on page 335, the putctl description refers to the box before it. The statement 
“section, below). On successful completion” should be “section, above). On successful 
completion”. 

In Appendix A on page 337, the box for testb () has a C statement 

int size, pri; 

that should be 

register size; 
uint pri; 


In Appendix A on page 341, under kernel. h is the statement 
struct timeval boottime I* time since system came up* Ihz 
that should be 

struct timeval boottime !* time since system came up*! 


In Appendix A on page 342, the square item at the bottom of the page has a period after the 
word QUEUE which should be a comma. 
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